%$Id$
%

\chapter{List of input commands}

Input commands are set in logical blocks, which are
marked by lines \texttt{\#NAME} - beginning of 
a block {\bf NAME} - and \texttt{\#endNAME} - end
of that block. Input commands are listed below 
sorted by blocks.

The file containing the input parameters ends with the keyword {\tt \#end}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Main}

The section should start with {\tt \#main} and finish with {\tt \#endmain}. 

\begin{itemize}

\item {\bf SpeciesList}={\it species-list}

Definition of the species used in the simulation, names of the species should
be the same as they are used in the source code. \\
{\tt SpeciesList=Na,H,O2PLUS,O\_THERMAL,NA\char`_Plus}

\item {\bf makefile}

Obsolete but still can be used. Introduces changes in the Makefile.\\
{\tt makefile MPIRUN=mpirun -np 16}\\
{\tt makefile SPICE=/Users/MyUser/MySpiceFolder} \\
{\tt makefile  SOURCES=src}  self-explanatory\\
{\tt makefile  RUNDIR=run}  self-explanatory\\
{\tt makefile ExternalModules}= [models/exosphere]


\item {\bf ForceRepeatableSimulationPath}=[off,on] \\ Force AMPS to run a repeatable calculations by disabling all code optimizations/procedures that are executed based on the actual execution time \\ {\tt ForceRepeatableSimulationPath=on} \\ {\tt  ForceRepeatableSimulationPath=off}  

\item {\bf DebuggerMode}=[off,on]

Switches ON/OFF debugger mode of execution

\item {\bf CouplerMode}=[off,swmf,ices]

Defines the mode of coupler execution, three are available:
\\{\tt CouplerMode=off} - no coupling, 
\\{\tt CouplerMode=swmf} - coupling within SWMF, 
\\{\tt CouplerMode=ices} - coupling using ICES tool.

\item {\bf SourceDirectory}={\it source-directory}

The directory where the main source code is located, usually it is
{\tt src} folder.\\
{\tt SourceDirectory=src}

\item {\bf ProjectSourceDirectory}={\it project-source-directory}

The directory where the source code for particular project is located.\\
{\tt ProjectSourceDirectory=srcEuropa}

\item {\bf WorkingSourceDirectory}={\it working-source-directory}

The directory where the code will be assembled and compiled
(choose the one that doesn't exist in the repository in order
to avoid deletion of source code files!)\\
{\tt WorkingSourceDirectory=srcTemp}

\item {\bf InputDirectory}={\it input-model-data-directory} \\ The location of the data files that will be used in the model run.

\item {\bf TrajectoryIntersectionWithBlockFaces}=[on,off]

\item {\bf StdOutErrorLog}=[off,on] \\ Switch (on/off) that controls output of the error messages on screen

\item {\bf TimeStepMode}=[SingleGlobalTimeStep,SpeciesGlobalTimeStep, \\ SingleLocalTimeStep,SpeciesLocalTimeStep]

Defines the way the time step is performed, four are available:
\\{\tt TimeStepMode=SingleGlobalTimeStep} - the same time step
for the entire domain and all species,
\\{\tt TimeStepMode=SpeciesGlobalTimeStep} - time step is different for
different species, but the same for the entire domain,
\\{\tt TimeStepMode=SingleLocalTimeStep} - time step is the same for all species, 
but differs within the domain,
\\{\tt TimeStepMode=SpeciesLocalTimeStep} - time step is different for different
species and differs within the domain.

\item {\bf ParticleWeightMode}=[SingleGlobalParticleWeight,SpeciesGlobalParticleWeight, \\ SingleLocalParticleWeight,SpeciesLocalParticleWeight]

Defines the way the statistical weights of particles are defined, for are available:
\\{\tt  ParticleWeightMode=SingleGlobalParticleWeight},
\\{\tt  ParticleWeightMode=SpeciesGlobalParticleWeight},
\\{\tt  ParticleWeightMode=SingleLocalParticleWeight},
\\{\tt  ParticleWeightMode=SpeciesLocalParticleWeight}.

\item {\bf ParticleWeightCorrectionMode}=[off,on] \\
Switches ON/OFF.

\item {\bf ErrorLog}={\it file-name}

Name of the file to write error information to.
\\{\tt ErrorLog=error.log}

\item {\bf Prefix}={\it prefix} \\ The prefix used for on screen output of AMPS  \\ {\tt Prefix=AMPS}

\item {\bf DiagnosticStream}=[screen,{\it file-name}] \\ The location of the diagnostic information output. The run-time diagnostic can be printed either on screen or in a file: \\  {\tt DiagnosticStream=amps.log} \\ {\tt DiagnosticStream=screen }  

\item {\bf OutputDirectory}={\it output-directory} \\ Name of the folder to write results to. \\ {\tt OutputDirectory=out}


\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {Species}

The file contains database of the physical parameters of the model species. During compilation the configuration script extract the parameters only of the species used in the current model runs.

The file must begin with {\tt \#species} and ends with {\tt \#endspecies}. The following are other commands 

\begin{itemize}

\item {\bf \#component}={\it specie-symbol} \\ Defines the symbolic name for the specie \\{\tt \#component=O}
\item {\bf mass}={\it molecule/atom mass-mass} \\ The molecule/atom mass [kg] \\ {\tt mass=16*\_AMU\_} 
\item {\bf charge}={\it electric-charge} \\ Electric charge [e] \\ {\tt charge=0}
\end{itemize}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Include}

Parts of the input parameters can be stored in separate files and included when the code is compiling using command {\tt \#include}. 

Example {\tt \#include species.input}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{UserDefinitions}
Obsolete but still can be used. Execution of AMPS can be controlled through files "UserDefinition.Exosphere.h", "UserDefinition.meshAMR.h", "UserDefinition.PIC.h", and "UserDefinition.PIC.PhysicalModelHeaderList.h" that contains some settings of the model.

The switch determines which of the files will be included into the sources of AMPS during compiling.

\begin{itemize}
\item {\bf Mesh} = [On/Off]
\item {\bf PIC} = [On/Off]
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{BackgroundSpecies} 
Describes interaction of the model particles with the background species


\begin{itemize}

\item {\bf BackgroundSpecies}=[on,off] \\ The switch defines whether the model will be used in the run.  

\item {\bf SpeciesList}={\it species-list} \\ The list of the background species used in the simulation. Example: 

{\tt SpeciesList=CO2,O}

\item {\bf CollisionMode}=[on,off] \\ The switch determines whether collisions with the background species will be simulated

\item {\bf LoadUserDefinitions}=[on,off],UserDefinitionsFileName={\it file-name} \\ Makes the compiler to include the file {\it file-name} in compiling. Example:

{\tt LoadUserDefinitions=on $\backslash\backslash$ \\ UserDefinitionsFileName=UserDefinition.PIC.BackgroundAtmosphere.h}

\item {\bf CollisionCrossSection}=[function,const] \\ Defines the collision cross section between the model particles and the background species. Parameters {\tt const} is used to define the hard sphere collision cross section, an {\tt function} is for a user-defined collision cross section. Example (function):  

{\tt CollisionCrossSection= function $\backslash\backslash$ \\ FunctionName={\it function-name} }

Example (const):

{\tt CollisionCrossSection= const $\backslash\backslash$ \\     const(Na,CO)=3e-15 $\backslash\backslash$ \\ const(Na,O)=3e-14}

\item {\bf CollisionScatteringAngle}=[function,isotropic] \\ Defines the model for distributing of the scattering angle after collision. {\tt isotropic} is for the isotropic angle distribution, and {\tt function} is for a user-defined function. Example (isotropic): 

{\tt CollisionScatteringAngle=isotropic}

Example (function): 

{\tt CollisionScatteringAngle=function $\backslash\backslash$ \\ FunctionName={\it function-name}} 

\item {\bf InjectConditionBackgroundParticle}=[on,off] \\ Inject background particle into the system is a injection condition is met.

\item {\bf RemoveConditionModelParticle}=[on,off] \\ Remove a model particle after collision with the background species if a condition is met.


\end{itemize}












%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{General}

\begin{itemize}
\item {\bf InitialSampleLength}={\it sample-length} \\ The number of iterations that will be used in the simulation. Could be changed during the run.

\item {\bf define} {\it macro macro-value} \\ Add definition of {\it macro} into pic/picGlobal.dfn

\item {\bf TrajectoryTracing}=[on, off] \\ Turns on and off the procedure for tracing of the individual particle trajectories

\item{\bf MaxSampledTrajectoryNumber}={\it toatl-sampled-trajectories-number} \\ The total number of the particle trajectories that will be traced for each species

\item {\bf MaxMeshRefinmentLevel}={\it max-mesh-refinment-level} \\ The maximum number of the refinement levels

\item {\bf EnforceRequestedMeshResolution}=[on,off] \\ Die if the requested mesh resolution is finer than that permitted by the settings of the model

\item {\bf TestRunTotalIteration}={\it iteration-number} \\ The number of the iterations before the output of the code test simulation results for the nightly test

\item {\bf ReferenceInjectionParticleNumber}={\it reference-number} \\ The number of the model particles that should be injected by the code each iterations. Used for evaluations of the particle weight.

\item {\bf NastranSurfaceUserData}=[on,off] \\ Use the NASTRAN surface 

\item {\bf ControlParticleInsideNastranSurface}=[on,off] \\ Check whether a particle is inside the surface defined by a NASTRAN mesh after finishing the particle moving step. Can significantly decrease the efficiency of the particle trajectory integration procedure. But can be useful for debugging. 

\item {\bf BlockCells}=[{\it nCells$_x$,nCells$_y$,nCells$_z$}] \\ The number of the "real" cells that populate a block in each direction

\item {\bf GhostCells}=[{\it nGhostCells$_x$,nGhostCells$_y$,nGhostCells$_z$}] \\ The number of the "ghost" cells that populate a block in each direction

\item {\bf MaxCutCellVolumeRelativeError}={\it error} \\ The maximum relative error of the volume calculation. Implemented cut-cells will make the error smaller than the requested value. Can significantly degrade the run-time of the volume calculation procedure without any benefit because the cut-faces will give enough accuracy. 

\item {\bf CutCellVolumeCalculationMaxRefinmentLevel}={\it max-refinment-level} \\ used in calculation of the cut-cell volume to limit the maximum refinement of the volume calculation (CutCell::GetRemainedBlockVolume). 

\end{itemize}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{ParticleCollisions}
The section described the particle collision model used in the simulation. The block has to begin with {\tt \#ParticleCollisions} and ends with {\tt endParticleCollisions}. Additional commands:
\begin{itemize}
\item {\bf model} = [off,HS] \\ the name of the model that will be used
\item {\bf SampleCollisionFrequency} = [on,off] \\ the switch turns sampling of the collision frequentcy
\item{\bf CollisionCrossSection}=[const,function] \\ defines a collision cross section \\ {\tt CollisionCrossSection=function {\it function-name}} 

{\tt CollisionCrossSection=const} \\ when constant collision cross section is used its value has to be defined for each pair of species with a constant or a function \\ {\tt const (H2O,H2O)= 2.0E-19} \\ if a collision cross section is not defined for a pair that its value is assumed being zero (no collisions between the species)
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Mesh}
The block contains settings of the AMPS mesh. The block begins with {\tt \#mesh} and ends with {\tt \#endmesh}.

\begin{itemize}
\item {\bf define} Macro {\it Macro-Value} \\ The value of the macro is saved in /src/meshAMR/meshAMRdef.h

\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Sampling}
The section controls the non-standard AMPS sampling routines. The section begins with {\tt \#Sampling} and ends with {\tt \#endSampling}.

\begin{itemize}
\item {\bf SampleParallelTangentialKineticTemperature}=[on,off], direction=[] \\
Turn on sampling of the parallel and tangential temperatures. The direction can be defined by a constant vector or a function \\ {\tt direction=const(lx,ly,lx)} \\ {\tt direction=function({\it function-name})}

\item {\bf VelocityDistributionSampling}=[on, off], x=(), nSampleIntervals,vmin,vmax \\
Define locations for sampling the velocity distribution function. {\it x} is the list of the locations, {\it nSampleIntervals} is the number of the intervals in the velocity space, and {\it xmin} and {\it xmax} are the minimum and maximum velocity limits of the distribution function. Example: 

 {\tt VelocityDistributionSampling=on !on,off $\backslash\backslash$   \\ x=(7.6E5,6.7E5,0.0), (2.8E5,5.6E5,0.0), (-2.3E5,3.0E5,0.0) $\backslash\backslash$ \\
   nSampleIntervals=500 $\backslash\backslash$ \\
   vmin=-40e3, vmax=40e3
}



\end{itemize}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{IDF}
The section defines the model of the internal degrees of freedom. The section has to begin with {\tt \#IDF} and ends with {\tt \#endIDF}. 

\begin{itemize}
\item {\bf Model}=[off,LB,qLB]
\item {\bf vtRelaxation}=[on,off]
\item {\bf rtRelaxation}=[on,off]
\item {\bf vvRelaxation}=[on,off]
\item {\bf nVibModes} \\ the number of the vibrational modes \\ Example: {\tt nVibModes(CO2=1,H2O=2)} 
\item {\bf nRotModes} \\ the number of the rotational modes \\ Example: {\tt nRotModes(CO2=2,H2O=3)}
\item {\bf RotZnum} \\ the rotational $Z_\nu$ number. $1/Z_\nu$ is the probability of the rotationa-translational energy exchange during a collision event. \\ {\tt RotZnum(H2O=3,CO2=2)}
\item {\bf VibTemp} \\ the characteristic vibrational temperature \\ {\tt  VibTemp(H2O=2000,CO2=1000)}

\item {\bf TemperatureIndex}{\it (spec$_1$, spec$_1$)=index} \\ Example:

{\tt TemperatureIndex(H2O,H2O)=0.5}

\end{itemize}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{UnimolecularReactions}

\begin{itemize}
\item {\bf UNIMOLECULARREACTIONS}=[on,off]

\item {\bf REACTIONLIFETIMEMULTIPLIER}={\it multiplier}

\item {\bf PROCESSOR}={\it function-name}

\item {\bf LIFETIMEUSERFUNCTION}={\it function-name}

\item {\bf REACTION} (PRODUCT, NONE), ID={\it reaction-symbolic-id}, LIFETIME



\end{itemize}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Exosphere}

Most of the description of the comet or planet environment will be done in this section. The following is the set of commands used in the section.

\begin{itemize} 
 

\item{\bf ReferenceGrounBasedObservationTime} 

\item{\bf SpiceKernels}

\item{\bf IcesLocationPath}={\it the path to ICES} \\ Location of ICES

\item{\bf IcesModelCase}={\it model-case} \\ the set of the BATSRUS restart files that will be used with ICES

\item{\bf Define} {\it Macro New-Macro-Value} \\ define {\it Macro}  

\item{\bf SurfaceDataStructure}=[default,{\it file-name}] \\ the command defines the data structure that is used by the exosphere model to keep its data on the surface of the internal boundary used in the simulation. The {\it default} data structure is a part of the exosphere model. The user can specify its own data structure by indicating the name of the header file ({\it file-name}) where the definition is located

\item {\bf SPICE}=[on,off] \\ the switch allows the model to use the SPICE routines

\item {\bf ExosphereSamplingMode}=[on,off] \\ ????

\item {\bf SimulationStartTime}={\it the start-time of the simulation} \\ Defines the physical time of the simulation. Needed when multiple astronomical bodies (Sun, planets) are involved in the simulation. \\
Example: {\tt SimulationStartTime=2009-01-24T00:00:00}

\item{\bf AddPhysicalModelHeader}={\it header-list} \\ The variable defines the list of headers where the project variables and functions are defined. \\ Example: {\tt addPhysicalModelHeader=Comet.h,Exosphere\_Helium.h}

\item {\bf PhotolyticReactions}=[on,off], ReactionProcessor=[],LifeTime=[]  \\ Describes the functions that are used for modeling of the photolytic reactions (photo-ionization, photo-dissociation)

ReactionProcessor is the function that is called by the core to model the reaction (inject the product of the reaction into the system) \\ {\tt ReactionProcessor=Comet::ExospherePhotoionizationReactionProcessor}

LifeTime is the function that returns the numerical value of the species lifetime depending of the locations of a particle (could be in a shadow of the planet) \\ 
{\tt LifeTime=Comet::ExospherePhotoionizationLifeTime} 


\item {\bf InitSurfaceSourceDistribution}={\it function-name} \\ Defines a user-defined function that is used for the initialization of the surface volatile distribution 

\item {\bf TypicalSolarWindConditions} = v(v$_x$,v$_y$,v$_z$), B(B$_x$,B$_y$,B$_z$), T, n \\ Definition of the typical solar wind conditions. Here, v, B, T, and n are bulk velocity, magnetic field, temperature, and number density of solar wind

\item {\bf SurfaceVolatileDensity}=[const, function] \\ Defines the number density of volatiles at the surface of the internal body. The number density could be given either by a constant or a function 
 
Example of a constant \\ {\tt SurfaceVolatileDensity=const  $\backslash\backslash$ \\ const(Na)=2.3E16}

Example of a function \\ {\tt SurfaceVolatileDensity=function $\backslash\backslash$ \\ function={\it function-name}}


\item {\bf AccommodationCoefficient}=[constant,function] \\ Defines the accommodation coefficient for modeling of the particle/surface interaction. The coefficient can be defined either by a set of the species-dependent constants or a function.

Example of a constant \\ {\tt AccommodationCoefficient=constant $\backslash\backslash$ \\ const(NA) = 0.2, const(NAPLUS)=0.2}

Example of a function \\ {\tt AccommodationCoefficient=function $\backslash\backslash$ \\ function={\it function-name}}


\item {\bf Source:ThermalDesorption}=[on,off],uThermal,VibrationalFrequency \\ Defines parameters of the thermal desorption (where it was described?)   . Example: \\ {\tt Source:ThermalDesorption=on $\backslash\backslash$ \\ uThermal(NA)=1.85*eV2J, VibrationalFrequency(NA)=1.0E13}
 

\item {\bf Source:PhotonStimulatedDesorption}= [on,off],PhotonFlux=[],CrossSection[],InjectionVelocityRange=[] \\ Parameters of the photon stimulated desorption injection model. Example: \\   {\tt Source:PhotonStimulatedDesorption=on $\backslash\backslash$ \\ PhotonFlux\_1AU=2.0E14*1.0E4 $\backslash\backslash$ \\ CrossSection(NA)=3.0E-21*1.0E-4, InjectionVelocityRange(NA)=(10,10.0E3)}

\item {\bf Source:ImpactVaporization}=[on,off],HeliocentricDistance=[],SourceRatePowerIndex=[], \\ SourceRate=[],SourceTemperature=[] \\ Impact vaporization model. Example: \\ {\tt Source:ImpactVaporization=on $\backslash\backslash$ \\ HeliocentricDistance=1.0*\_AU\_ $\backslash\backslash$ \\ SourceRatePowerIndex=0.0 $\backslash\backslash$ \\ SourceRate(H2O)=2.0E26, SourceTemperature(H2O)=200.0} 

\item {\bf Source:Sputtering}=[on,off], Yield=[], InjectionVelocityRange=[] \\ Sputtering model. Example: \\ {\tt Source:Sputtering=on $\backslash\backslash$ \\ Yield(NA)=0.1, InjectionVelocityRange(NA)=(10,10.0E3)}


\item {\bf Source:VerticalInjection}=[on,off], SourceRate[], BulkVelocity[] \\
the source model generates particles moving vertically to the local normal with constant bulk velocity. the source model is useful for testing purposes. Example: \\ {\tt Source:VerticalInjection=on $\backslash\backslash$ \\ SourceRate(O2)=1.69E22, BulkVelocity(O2)=6000.0}


\item {\bf Source:ExternalDomainBoundaryInjection}=[on,off] \\ Initialize the injection processes ID for particle injection through the external boundary of the domain

\item{\bf Source:DefineSourceID}={\it user-defined-source-id} \\ can be use to register in AMPS' core a user-defined ID for a source process. The id is saved as a macro \_EXOSPEHRE\_SOURCE\_\_ID\_\_USER\_DEFINED\_\_{\it user-defined-source-id}{\tt \_} in the file Exosphere.dfn. The ID can be use to distinguish particles that are produced via different source processes for the sampling purposes.



\item {\bf Source:UserDefined}=[on,off], SourceProcessCode={\it code}, SourceRate={\it function-name}, \\ GenerateParticleProperties={\it function-name}, ModifySurfaceSpeciesAbundance=[true,false], \\ InitSurfaceSourceDistribution={\it function-name} 

The structure describe the user defined particle injection boundary conditions. Example: \\ {\tt Source:UserDefined=on $\backslash\backslash$ \\ SourceProcessCode=Jet $\backslash\backslash$ \\ SourceRate=Comet::GetTotalProductionRateJet $\backslash\backslash$ \\ GenerateParticleProperties=Comet::GenerateParticlePropertiesBjorn $\backslash\backslash$ \\ ModifySurfaceSpeciesAbundance=false  $\backslash\backslash$ \\ InitSurfaceSourceDistribution=HeliumDesorption::SurfaceInjectionDistribution.Init}



\end{itemize}











     

\section{Additional parameters that are needed} 
1. The accuracy of the volume calculation of the cut-cells (meshAMRgeneric.h\%8286)








